数据库界的Swagger：一键生成数据库文档！你不了解一下？
The following article is from 芋道源码 Author 老艿艿
对于API的文档，我们有Swagger等工具来自动生成了。但有有一类文档还是常常困扰着我们，那就是数据库表结构的文档。相信很多同学都有过手写数据库表结构文档 的经历吧？常规操作就是一通无脑的 CV 大法，产出一份小几十页的 Word 文档。
那么，是否有什么工具，可以帮我们偷懒高效的自动 生成数据库表结构文档呢？
还真有！下面就来介绍这样一个工具：screw！
2. screw 简介
screw 是一个简洁好用的数据库表结构文档的生成工具 ，支持 MySQL、Oracle、PostgreSQL 等主流的关系数据库。
screw 的仓库地址是 https://github.com/pingfangushi/screw，感兴趣的胖友，可以研究一波。
生成的文档有 HTML、Word、Markdown 三种格式 ，示例如下图所示：
| 格式 | 图 |
|---|---|
| HTML | |
| Word | |
| Markdown |
3. 快速入门
screw 有两种方式 来生成文档，通过 Java 代码 或者 Maven 插件 。
下面，我们来分别快速入门下。
3.1 使用 Java 代码的方式
创建 lab-70-db-doc-screw-01 示例项目，使用 screw 的 Java 代码 的方式，生成文档。
3.1.1 引入依赖
在 pom.xml 文件中，引入 screw 的依赖 screw-core。
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<parent>
<artifactId>lab-70-db-doc</artifactId>
<groupId>cn.iocoder.springboot.labs</groupId>
<version>1.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>lab-70-db-doc-screw-01</artifactId>
<dependencies>
<!-- screw 库，简洁好用的数据库表结构文档生成器 -->
<dependency>
<groupId>cn.smallbun.screw</groupId>
<artifactId>screw-core</artifactId>
<version>1.0.5</version>
</dependency>
<!-- 数据库连接 -->
<dependency>
<groupId>com.zaxxer</groupId>
<artifactId>HikariCP</artifactId>
<version>3.4.5</version>
</dependency>
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<version>8.0.22</version>
</dependency>
</dependencies>
</project>
依赖 HikariCP 和 mysql-connector-java 是为了连接 MySQL 数据库。
3.1.2 ScrewMain
创建 ScrewMain 类，使用 screw 生成文档。代码如下：
public class ScrewMain {
private static final String DB_URL = "jdbc:mysql://400-infra.server.iocoder.cn:3306";
private static final String DB_NAME = "mall_system";
private static final String DB_USERNAME = "root";
private static final String DB_PASSWORD = "3WLiVUBEwTbvAfsh";
private static final String FILE_OUTPUT_DIR = "/Users/yunai/screw_test";
private static final EngineFileType FILE_OUTPUT_TYPE = EngineFileType.HTML; // 可以设置 Word 或者 Markdown 格式
private static final String DOC_FILE_NAME = "数据库文档";
private static final String DOC_VERSION = "1.0.0";
private static final String DOC_DESCRIPTION = "文档描述";
public static void main(String[] args) {
// 创建 screw 的配置
Configuration config = Configuration.builder()
.version(DOC_VERSION) // 版本
.description(DOC_DESCRIPTION) // 描述
.dataSource(buildDataSource()) // 数据源
.engineConfig(buildEngineConfig()) // 引擎配置
.produceConfig(buildProcessConfig()) // 处理配置
.build();
// 执行 screw，生成数据库文档
new DocumentationExecute(config).execute();
}
/**
* 创建数据源
*/
private static DataSource buildDataSource() {
// 创建 HikariConfig 配置类
HikariConfig hikariConfig = new HikariConfig();
hikariConfig.setDriverClassName("com.mysql.cj.jdbc.Driver");
hikariConfig.setJdbcUrl(DB_URL + "/" + DB_NAME);
hikariConfig.setUsername(DB_USERNAME);
hikariConfig.setPassword(DB_PASSWORD);
hikariConfig.addDataSourceProperty("useInformationSchema", "true"); // 设置可以获取 tables remarks 信息
// 创建数据源
return new HikariDataSource(hikariConfig);
}
/**
* 创建 screw 的引擎配置
*/
private static EngineConfig buildEngineConfig() {
return EngineConfig.builder()
.fileOutputDir(FILE_OUTPUT_DIR) // 生成文件路径
.openOutputDir(false) // 打开目录
.fileType(FILE_OUTPUT_TYPE) // 文件类型
.produceType(EngineTemplateType.freemarker) // 文件类型
.fileName(DOC_FILE_NAME) // 自定义文件名称
.build();
}
/**
* 创建 screw 的处理配置，一般可忽略
* 指定生成逻辑、当存在指定表、指定表前缀、指定表后缀时，将生成指定表，其余表不生成、并跳过忽略表配置
*/
private static ProcessConfig buildProcessConfig() {
return ProcessConfig.builder()
.designatedTableName(Collections.<String>emptyList()) // 根据名称指定表生成
.designatedTablePrefix(Collections.<String>emptyList()) //根据表前缀生成
.designatedTableSuffix(Collections.<String>emptyList()) // 根据表后缀生成
.ignoreTableName(Arrays.asList("test_user", "test_group")) // 忽略表名
.ignoreTablePrefix(Collections.singletonList("test_")) // 忽略表前缀
.ignoreTableSuffix(Collections.singletonList("_test")) // 忽略表后缀
.build();
}
}
代码比较简单，胖友看看注释即可。
比较重要的变量，已经抽取成静态 变量，胖友看着修改哈。
3.1.3 简单测试
执行 ScrewMain 程序，进行文档的生成。这里我们生成的是 HTML 文档，效果如下图所示：
3.2 使用 Maven 插件的方式
创建 lab-70-db-doc-screw-02 示例项目，使用 screw 的 Maven 插件 的方式，生成文档。
3.2.1 引入插件
在 pom.xml 文件中，引入 screw 的插件 screw-maven-plugin。
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<parent>
<artifactId>lab-70-db-doc</artifactId>
<groupId>cn.iocoder.springboot.labs</groupId>
<version>1.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>lab-70-db-doc-screw-02</artifactId>
<build>
<plugins>
<plugin>
<groupId>cn.smallbun.screw</groupId>
<artifactId>screw-maven-plugin</artifactId>
<version>1.0.5</version>
<dependencies>
<!-- 数据库连接 -->
<dependency>
<groupId>com.zaxxer</groupId>
<artifactId>HikariCP</artifactId>
<version>3.4.5</version>
</dependency>
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<version>8.0.22</version>
</dependency>
</dependencies>
<configuration>
<!-- 数据库相关配置 -->
<driverClassName>com.mysql.cj.jdbc.Driver</driverClassName>
<jdbcUrl>jdbc:mysql://400-infra.server.iocoder.cn:3306/mall_system</jdbcUrl>
<username>root</username>
<password>3WLiVUBEwTbvAfsh</password>
<!-- screw 配置 -->
<fileType>HTML</fileType>
<title>数据库文档</title> <!--标题-->
<fileName>测试文档名称</fileName> <!--文档名称 为空时:将采用[数据库名称-描述-版本号]作为文档名称-->
<description>数据库文档生成</description> <!--描述-->
<version>${project.version}</version> <!--版本-->
<openOutputDir>false</openOutputDir> <!--打开文件输出目录-->
<produceType>freemarker</produceType> <!--生成模板-->
</configuration>
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>run</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
Maven 插件的配置项 比较少，胖友按需修改下 <configuration/> 即可。
3.2.2 简单测试
执行 screw-maven-plugin 插件，会在 doc 目录下生成文档。如下图所示：
4. 生成实体类
screw 的实现原理，是基于数据库中的表结构 ，生成对应的文档。
那么，是否可以自动 生成 Java 实体类呢？答案是可以的，在 screw-extension 项目中，拓展 提供了该功能。
这样，日常开发中，在我们完成数据库的建表 之后，可以直接生成对应的 Java 实体类，避免枯燥的重复劳动。
下面，我们来快速入门下。创建 lab-70-db-doc-screw-03 示例项目，使用 screw 的 Java 代码 的方式，生成 Java 实体类。
4.1 引入依赖
在 pom.xml 文件中，额外 引入 screw 的依赖 screw-extension。
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<parent>
<artifactId>lab-70-db-doc</artifactId>
<groupId>cn.iocoder.springboot.labs</groupId>
<version>1.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>lab-70-db-doc-screw-03</artifactId>
<dependencies>
<!-- screw 库，简洁好用的数据库表结构文档生成器 -->
<dependency>
<groupId>cn.smallbun.screw</groupId>
<artifactId>screw-core</artifactId>
<version>1.0.5</version>
</dependency>
<dependency>
<groupId>cn.smallbun.screw</groupId>
<artifactId>screw-extension</artifactId>
<version>1.0.5</version>
</dependency>
<!-- 数据库连接 -->
<dependency>
<groupId>com.zaxxer</groupId>
<artifactId>HikariCP</artifactId>
<version>3.4.5</version>
</dependency>
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<version>8.0.22</version>
</dependency>
</dependencies>
</project>
友情提示：由于
screw-extension项目处于初步开发阶段，暂时未将该依赖推到 Maven 中央仓库，所以需要自己克隆项目，进行编译打包到本地。
4.2 ScrewMain
创建 ScrewMain 类，使用 screw 生成 Java 实体类。代码如下：
public class ScrewMain {
private static final String DB_URL = "jdbc:mysql://400-infra.server.iocoder.cn:3306";
private static final String DB_NAME = "mall_system";
private static final String DB_USERNAME = "root";
private static final String DB_PASSWORD = "3WLiVUBEwTbvAfsh";
private static final String FILE_OUTPUT_DIR = "/Users/yunai/screw_test";
private static final String JAVA_CLASS_PACKAGE = "cn.iocoder.dataobject";
public static void main(String[] args) {
// 创建 screw 的配置
PojoConfiguration config = PojoConfiguration.builder()
.path(FILE_OUTPUT_DIR) // 生成 POJO 相关的目录
.packageName(JAVA_CLASS_PACKAGE) // 包名
.nameStrategy(new HumpNameStrategy()) // 包名策略
.useLombok(false) // 是否使用 Lombok
.dataSource(buildDataSource()) // 数据源
.processConfig(buildProcessConfig()) // 处理配置
.build();
// 执行 screw，生成 POJO 实体类
new PojoExecute(config).execute();
}
/**
* 创建数据源
*/
private static DataSource buildDataSource() {
// 创建 HikariConfig 配置类
HikariConfig hikariConfig = new HikariConfig();
hikariConfig.setDriverClassName("com.mysql.cj.jdbc.Driver");
hikariConfig.setJdbcUrl(DB_URL + "/" + DB_NAME);
hikariConfig.setUsername(DB_USERNAME);
hikariConfig.setPassword(DB_PASSWORD);
hikariConfig.addDataSourceProperty("useInformationSchema", "true"); // 设置可以获取 tables remarks 信息
// 创建数据源
return new HikariDataSource(hikariConfig);
}
/**
* 创建 screw 的处理配置，一般可忽略
* 指定生成逻辑、当存在指定表、指定表前缀、指定表后缀时，将生成指定表，其余表不生成、并跳过忽略表配置
*/
private static ProcessConfig buildProcessConfig() {
return ProcessConfig.builder()
.designatedTableName(Collections.<String>emptyList()) // 根据名称指定表生成
.designatedTablePrefix(Collections.<String>emptyList()) //根据表前缀生成
.designatedTableSuffix(Collections.<String>emptyList()) // 根据表后缀生成
.ignoreTableName(Arrays.asList("test_user", "test_group")) // 忽略表名
.ignoreTablePrefix(Collections.singletonList("test_")) // 忽略表前缀
.ignoreTableSuffix(Collections.singletonList("_test")) // 忽略表后缀
.build();
}
}
代码比较简单，胖友看看注释即可。不同于上面的快速入门，这里我们使用 PojoConfiguration 作为配置类，使用 PojoExecute 作为执行器。
比较重要的变量，已经抽取成静态 变量，胖友看着修改哈。
如果您正在学习Spring Boot，推荐一个连载多年还在继续更新的免费教程：http://blog.didispace.com/spring-boot-learning-2x/
4.3 简单测试
执行 ScrewMain 程序，进行 Java 实体类的生成。效果如下图所示：
生成的 Java 实体类的成员属性 还不太正确，需要等待作者进行下修复。
666. 彩蛋
至此，我们已经完成 screw 的学习，一起来简单总结下：
screw 支持生成数据库表结构文档 ，通过 Java 代码或者 Maven 插件的方式。 screw 支持生成 Java 实体类 ，通过 screw-extension提供。
初略喵了下 screw 的代码，总体代码量在 5000+ 行，核心代码在 2000 行左右。项目分层干净，代码注释完成，胖友可以选择阅读了解下。这样，我们可以根据我们实际项目的需要，进行二次开发 。
往期推荐
最近有很多人问，有没有读者交流群，想知道怎么加入。加入方式很简单，有兴趣的同学，只需要点击下方卡片，回复“加群“，即可免费加入我们的高质量技术交流群！
点击阅读原文，送你免费Spring Boot教程！